Skip to main content
Codeflash is installed and configured on a per-project basis. You can install Codeflash locally for a project by running the following command in the project’s virtual environment:

​
Prerequisites

Before installing Codeflash, ensure you have:
  1. Python 3.9 or above installed
  2. A Python project with a virtual environment
  3. Project dependencies installed in your virtual environment
  4. Tests (optional) for your code (Codeflash uses tests to verify optimizations)
Virtual Environment RequiredAlways install Codeflash in your project’s virtual environment, not globally. Make sure your virtual environment is activated before proceeding.
# Example: Activate your virtual environment
source venv/bin/activate  # On Linux/Mac
# or
#venv\Scripts\activate     # On Windows
1

Install Codeflash

pip install codeflash
Codeflash is a Development DependencyWe recommend installing Codeflash as a development dependency. It doesn’t need to be installed as part of your package requirements. Codeflash is intended to be used locally and as part of development workflows such as CI.
[tool.poetry.dependencies.dev]
codeflash = "^latest"
2

Generate a Codeflash API Key

Codeflash uses cloud-hosted AI models to optimize your code. You’ll need an API key to use it.
  1. Visit the Codeflash Web App
  2. Sign up with your GitHub account (free)
  3. Navigate to the API Key page to generate your API key
Free Tier AvailableCodeflash offers a free tier with a limited number of optimizations per month. Perfect for trying it out or small projects!
3

Run Automatic Configuration

Navigate to your project’s root directory (where your pyproject.toml file is or should be) and run:
# Make sure you're in your project root
cd /path/to/your/project

# Run the initialization
codeflash init
If you don’t have a pyproject.toml file yet, the codeflash init command will ask you to create one
What’s pyproject.toml?pyproject.toml is a configuration file that is used to specify build tool settings for Python projects. pyproject.toml is the modern replacement for setup.py and requirements.txt files. It’s the new standard for Python package metadata.
When running codeflash init, you will see the following prompts:
1. Enter your Codeflash API key: 
2. Which Python module do you want me to optimize going forward? (e.g. my_module)
3. Where are your tests located? (e.g. tests/)
4. Which test framework do you use? (pytest/unittest)
After you have answered these questions, Codeflash will be configured for your project. The configuration will be saved in the pyproject.toml file in the root directory of your project. To understand the configuration options, and set more advanced options, see the Configuration page.

​
Step 4: Install the Codeflash GitHub App

Finally, if you have not done so already, Codeflash will ask you to install the Github App in your repository. The Codeflash GitHub App allows access to your repository to the codeflash-ai bot to open PRs, review code, and provide optimization suggestions. Please install the Codeflash GitHub app by choosing the repository you want to install Codeflash on.

​
Try It Out!

  • Quick Start
  • Example Project
Once configured, you can start optimizing your code immediately:
# Optimize a specific function
codeflash --file path/to/your/file.py --function function_name

# Or optimize locally without creating a PR
codeflash --file path/to/your/file.py --function function_name --no-pr
Pro tip: Start with a single function to see how Codeflash works before running it on your entire codebase.

​
Troubleshooting

Make sure:
  • ✅ Your virtual environment is activated
  • ✅ All project dependencies are installed
# Verify your virtual environment is active
which python  # Should show path to your venv

# Install missing dependencies
pip install -r requirements.txt
Use the --verbose flag for detailed output:
codeflash optimize --verbose
This will show:
  • 🔍 Which functions are being analyzed
  • 🚫 Why certain functions were skipped
  • ⚠️ Detailed error messages
  • 📊 Performance analysis results
Common Reasons Functions Are Skipped:
  • Function is too simple (less than 3 lines)
  • Function has no clear performance bottleneck
  • Function contains unsupported constructs
Verify:
  • 📁 Your test directory path is correct in pyproject.toml
  • 🔍 Tests are discoverable by your test framework
  • 📝 Test files follow naming conventions (test_*.py for pytest)
# Test if pytest can discover your tests
pytest --collect-only

# Check your pyproject.toml configuration
cat pyproject.toml | grep -A 5 "\[tool.codeflash\]"

​
Next Steps